home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 May / EnigmA AMIGA RUN 18 (1997)(G.R. Edizioni)(IT)[!][issue 1997-05][EAR-CD II].iso / softwareupdate / system / amigados / miscellaneous / functions.doc < prev    next >
Text File  |  1996-10-10  |  10KB  |  291 lines
  1. 8    MISCELLANEOUS - FUNCTIONS
  2.  
  3. 8.1  QUICK REFERENCE
  4.  
  5. Here is a complete list of the functions described in this
  6. chapter:
  7.  
  8.   Function       Description                                   
  9.   -------------------------------------------------------------
  10.   Execute()      Executes "Shell" commands from C.
  11.   IoErr()        Returns the last AmigaDOS error message.
  12.   SetIoErr()     Alters the global dos error variable.
  13.   -------------------------------------------------------------
  14.  
  15.  
  16.  
  17. ---------------------------------------------------------------
  18.  
  19. Execute()
  20.  
  21. ROM library: "dos.library/Execute", (Any Version)
  22. #include <clib/dos_protos.h>
  23.  
  24. Executes "Shell" commands from C.
  25.  
  26. Synopsis:     ok = Execute( com_str, def_input, def_output );
  27.   
  28.   ok:         (LONG) If the command could successfully be
  29.               launched TRUE will be returned, else FALSE is
  30.               returned.
  31.               
  32.               Please note that the function will not wait for
  33.               the executed program to be completed, and the
  34.               function can consequently not know if the
  35.               executed program finished its task successfully
  36.               or failed. The returned value indicates only if
  37.               the program was successfully started (launched)
  38.               or not.
  39.  
  40.   com_str:    (STRPTR) Pointer to a string which contains the
  41.               command line you want to have executed. Here are
  42.               some examples:
  43.                 "Dir"
  44.                 "C:Dir RAM: All" 
  45.                 "C:Copy DH0:Car.doc to DF1:"
  46.                 "MyPaintProg Flowers.pic"
  47.  
  48.   def_input:  (BPTR) Pointer to the "default input handler".
  49.               This filed is usually set to NULL, since a
  50.               default input handler is usually not needed.
  51.  
  52.               See chapter 6 "Handlers" for more information
  53.               about handlers.
  54.  
  55.   def_output: (BPTR) Pointer to the "default output handler".
  56.  
  57.               See chapter 6 "Handlers" for more information
  58.               about handlers.
  59.               
  60.               If the program you executed do not use the
  61.               default output handler you can set this field
  62.               to NULL.
  63.  
  64. Note! The "run" program must be available in the "C:" directory
  65. if you use Execute() with dos library V34 or earlier.
  66.  
  67. Here is a simple example on how to use the Execute() function:
  68.  
  69.   /* Store the result code here: */
  70.   BOOL ok;
  71.   
  72.   /* A "BCPL" pointer to our "default output */
  73.   /* handler": (a Console Window)            */
  74.   BPTR my_console;
  75.  
  76.   - - -
  77.  
  78.   /* Open a Console Window which will be used as our */
  79.   /* default output handler:                         */
  80.   my_console = 
  81.    Open( "CON:0/0/640/100/Test/CLOSE/WAIT", MODE_NEWFILE );
  82.  
  83.   /* Have we successfully opened the Console Window? */
  84.   if( !my_console )
  85.     exit( 20 ); /* Exit with an error code: */
  86.  
  87.   
  88.   /* Execute the "Shell" command "Dir". We do not use */
  89.   /* and "input" handler, and the "output" should be  */
  90.   /* sent to our Console Window.                      */
  91.   ok = Execute( "C:Dir RAM:", NULL, my_console );
  92.  
  93.   /* OK? */
  94.   if( ok )
  95.     printf( "The \"Shell\" command was successfully executed!\n" );
  96.   else
  97.     printf( "Error! Could not execute the \"Shell\" command!\n" );
  98.  
  99.   - - -
  100.  
  101.   /* Close the Console Window: */
  102.   Close( my_console );
  103.  
  104.  
  105. See also: Open(), Close()
  106.  
  107. ---------------------------------------------------------------
  108.  
  109. IoErr()
  110.  
  111. ROM library: "dos.library/IoErr", (Any Version)
  112. #include <clib/dos_protos.h>
  113.  
  114. Returns the last AmigaDOS error message.
  115.  
  116. Synopsis:     error_code = IoErr();
  117.  
  118.   error_code: (LONG) The function will return one of the below
  119.               listed error flags: (The flags are defined in
  120.               header file "dos/dos.h")
  121.  
  122.               ERROR_NO_FREE_STORE:
  123.                 Out of memory!
  124.               ERROR_TASK_TABLE_FULL: 
  125.                 To many processes running!
  126.               ERROR_BAD_TEMPLATE: 
  127.                 Incorrect command line template!
  128.               ERROR_BAD_NUMBER: 
  129.                 Incorrect number/value!
  130.               ERROR_REQUIRED_ARG_MISSING: 
  131.                 Required arguemnt was not set!
  132.               ERROR_KEY_NEEDS_ARG: 
  133.                 The argument after the keyword is missing!
  134.               ERROR_TOO_MANY_ARGS: 
  135.                 Too many arguments on the command line!
  136.               ERROR_UNMATCHED_QUOTES: 
  137.                 Incorrect number of quotations!
  138.               ERROR_LINE_TOO_LONG: 
  139.                 Too long command line!
  140.               ERROR_FILE_NOT_OBJECT: 
  141.                 The file can not be found and/or executed
  142.               ERROR_INVALID_RESIDENT_LIBRARY: 
  143.                 The AmigaDOS library is too old!
  144.               ERROR_NO_DEFAULT_DIR: 
  145.                 There does not exist a default directory!
  146.               ERROR_OBJECT_IN_USE: 
  147.                 The object is currently used and is locked!
  148.               ERROR_OBJECT_EXISTS: 
  149.                 The object already exist and can not be deleted!
  150.               ERROR_DIR_NOT_FOUND: 
  151.                 Unknown directory!
  152.               ERROR_OBJECT_NOT_FOUND: 
  153.                 Unknown file or device!
  154.               ERROR_BAD_STREAM_NAME: 
  155.                 The string contained invalid commands/parameters!
  156.               ERROR_OBJECT_TOO_LARGE: 
  157.                 The object is too big!
  158.               ERROR_ACTION_NOT_KNOWN: 
  159.                 Impossible command used on a device!
  160.               ERROR_INVALID_COMPONENT_NAME: 
  161.                 Too long name or invalid signs used!
  162.               ERROR_INVALID_LOCK: 
  163.                 Invalid type of lock used!
  164.               ERROR_OBJECT_WRONG_TYPE: 
  165.                 Incorrect object type used!
  166.               ERROR_DISK_NOT_VALIDATED: 
  167.                 The disk has not yet been validated or is damaged!
  168.               ERROR_DISK_WRITE_PROTECTED: 
  169.                 The disk is write protected!
  170.               ERROR_RENAME_ACROSS_DEVICES: 
  171.                 Can not rename an object to another device!
  172.               ERROR_DIRECTORY_NOT_EMPTY: 
  173.                 Can not delete the directory since it is not empty!
  174.               ERROR_TOO_MANY_LEVELS: 
  175.                 Too many soft links used!
  176.               ERROR_DEVICE_NOT_MOUNTED: 
  177.                 Device not available!
  178.               ERROR_SEEK_ERROR: 
  179.                 Tried to move the file cursor outside the file!
  180.               ERROR_COMMENT_TOO_BIG: 
  181.                 Too long comment used!
  182.               ERROR_DISK_FULL: 
  183.                 The disk is full!
  184.               ERROR_DELETE_PROTECTED: 
  185.                 The object is protected from being deleted!
  186.               ERROR_WRITE_PROTECTED: 
  187.                 The object is protected from being overwritten
  188.               ERROR_READ_PROTECTED: 
  189.                 The object is protected from being read!
  190.               ERROR_NOT_A_DOS_DISK: 
  191.                 The disk is not of AmigaDOS format!
  192.               ERROR_NO_DISK: 
  193.                 No disk in the drive!
  194.               ERROR_NO_MORE_ENTRIES: 
  195.                 No more objects in the directory!
  196.  
  197.               ERROR_IS_SOFT_LINK: 
  198.                 Can not do it on a soft link!
  199.               ERROR_OBJECT_LINKED: 
  200.                 The object is linked!
  201.               ERROR_BAD_HUNK: 
  202.                 Incorect hunk found!
  203.               ERROR_NOT_IMPLEMENTED: 
  204.                 The feature has not been implemented yet!
  205.               ERROR_RECORD_NOT_LOCKED: 
  206.                 The record was not locked!
  207.               ERROR_LOCK_COLLISION: 
  208.                 Two locks collided!
  209.               ERROR_LOCK_TIMEOUT: 
  210.                 The time to get the lock has expired!
  211.               ERROR_UNLOCK_ERROR: 
  212.                 Problems with unlocking the object!
  213.  
  214.               ERROR_BUFFER_OVERFLOW:
  215.                 Some internal buffer was too small!
  216.               ERROR_BREAK:
  217.                 The executin was stopped!
  218.               ERROR_NOT_EXECUTABLE:
  219.                 The file is protected from being executed!
  220.  
  221. Please note that all dos function does not use the global error
  222. code! You should therefore, of course, only use it when you
  223. have been told that it will work.
  224.  
  225. Here is a simple example on how to use the IoErr() function:
  226.  
  227.   /* Store the error code here: */
  228.   LONG error_code;
  229.  
  230.   - - -
  231.  
  232.   /* Collect the global error code: */
  233.   error_code = IoErr();
  234.  
  235.   /* Print the error code: */
  236.   printf( "Error code: %d - ", error_code );
  237.  
  238.   /* Examine the error code: */  
  239.   switch( error_code )
  240.   {
  241.     case ERROR_NO_FREE_STORE: printf( "Out of memory!\n" ); break;
  242.     case ERROR_TASK_TABLE_FULL: printf( "To many processes running!\n" ); 
  243. break;
  244.  
  245.     /* and so on... */
  246.  
  247.     default:
  248.       printf( "Unknown error reported!\n" );
  249.   }
  250.  
  251.  
  252. See also: SetIoErr()
  253.  
  254. ---------------------------------------------------------------
  255.  
  256. SetIoErr()
  257.  
  258. ROM library: "dos.library/SetIoErr", (V36+)
  259. #include <clib/dos_protos.h>
  260.  
  261. Alters the global dos error variable.
  262.  
  263. Synopsis:    old_value = SetIoErr( new_value );
  264.   
  265.   old_value: (LONG) The function will return the "old" error
  266.              value. See "IoErr()" for more information about
  267.              the possible error codes.
  268.  
  269.   new_value: (LONG) The new value you want to store in the
  270.              global error variable. When you want to "clear"
  271.              the variable you should set this field to 0.
  272.  
  273. Here is a simple example on how to use the SetIoErr() function:
  274.  
  275.   /* Store the "old" error code here: */
  276.   LONG old_error_code;
  277.  
  278.   - - -
  279.  
  280.   /* Set the global error variable to 0: */
  281.   /* ("Clear" the global error variable) */
  282.   old_error_code = SetIoErr( 0 );
  283.  
  284.   /* Print the "old" error code: */
  285.   printf( "Old error code: %d\n", old_error_code );
  286.  
  287.  
  288. See also: IoErr()
  289.  
  290. ---------------------------------------------------------------
  291.